Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 1 - Appearance Manager Reference / Appearance Manager Functions

Drawing Appearance-Compliant Menus /

DrawThemeMenuItem

NEW WITH THE APPEARANCE MANAGER

Draws a menu item that coordinates with the current theme.

pascal OSStatus DrawThemeMenuItem (
                     const Rect *inMenuRect,
                     const Rect *inItemRect,
                     SInt16 inVirtualMenuTop,
                     SInt16 inVirtualMenuBottom,
                     ThemeMenuState inState,
                     ThemeMenuItemType inItemType,
                     MenuItemDrawingUPP inDrawProc,
                     UInt32 inUserData);

inMenuRect

On input, a pointer to a rectangle that should contain the area of the entire menu; this is the actual menu rectangle as used in your menu definition function.

inItemRect

On input, a pointer to a rectangle, which should contain the area of the entire menu item. The menu item's background will be drawn in the rectangle passed in the inItemRect parameter. You should calculate the size of the menu item's content and then call GetThemeMenuItemExtra to get the amount of padding surrounding menu items in the current theme; the width and height of the menu item rectangle are determined by adding these values together.

inVirtualMenuTop

An integer representing the true top of the menu. Normally this value is the top coordinate of the rectangle supplied in the inMenuRect parameter. This value could be different, however, if a menu is scrolled or bigger than can be displayed in the menu rectangle. You would normally pass the value of the global variable TopMenuItem into this parameter if you are writing a custom menu definition function.

inVirtualMenuBottom

An integer representing the true bottom of the menu. Normally this value is the bottom coordinate of the rectangle supplied in the inMenuRect parameter. This value could be different, however, if a menu is scrolled or bigger than can be displayed in the menu rectangle. You would normally pass the value of the global variable AtMenuBottom into this parameter if you are writing a custom menu definition function.

inState

A value specifying the state (active, selected, or disabled) in which the menu item is to be drawn; see "Appearance-Compliant Menu Draw State Constants".

inItemType

A constant of type ThemeMenuItemType. If you pass kThemeMenuItemScrollUpArrow or kThemeMenuItemScrollDownArrow, then pass nil for the inDrawProc parameter, since there's no content to be drawn. If you pass kThemeMenuItemHierarchical, the hierarchical arrow is drawn for you. See "Appearance-Compliant Menu Item Type Constants".

inDrawProc

On input, a pointer to your menu item drawing function. The value of the inDrawProc parameter can be a valid universal procedure pointer or nil; see MyMenuItemDrawingProc.

inUserData

Data to be passed in to the inUserData parameter of MyMenuItemDrawingProc. This data is usually a pointer to information needed to draw the item's contents, such as a pointer to a string.

function result

A result code; see "Result Codes".

DISCUSSION

The DrawThemeMenuItem function should be called when you are writing your own custom menu definition function and wish to coordinate menu items with the current theme. Your menu drawing function will be called clipped to the rectangle in which you are allowed to draw your content; do not draw outside this region. At the time your menu drawing function is called, the foreground text color and mode are already set to draw text in the specified state (enabled, selected, disabled) and correct color for the theme. You do not need to set the color unless you have special drawing needs.

IMPORTANT

You should not depend on the background color for your menu item, so you should not call the EraseRect function from your menu item drawing function.

SPECIAL CONSIDERATIONS

Make sure Appearance Manager 1.0.1 is present before calling the DrawThemeMenuItem function. See "Appearance Manager Gestalt Selector Constants" for details on how to determine if the Appearance Manager is present and what its version is, if so.